package a5.function;

import java.util.LinkedList;

/**
 * <pre>
 * Provides an interface for invoking functions for an {@link a5.Interpreter Interpreter}. 
 * A typical {@code Function} will contain a set of {@link a5.grammar.annotations.Grammar Production} rules
 * which govern how the function iterates through the program text associated with the interpreter. 
 * Additionally, the function should hold a reference to the beginning of the function within the 
 * interpreter's program text and be able to restore interpreter to the point of execution immediately
 * after the requested function invocation. 
 * </pre>
 * 
 * @author Jason Campos
 * @version Assignment 5, CS 152 (Programming Paradigms) Fall 2012, Jeffrey Smith
 */
public interface Function {
	
	/**
	 * <pre>
	 * The interface method for invoking the defined function with a set of arguments.
	 * 
	 * If the implementations of this method uses the {@link a5.common.ProgramCursor ProgramCursor}
	 * to manipulate the point of program execution, it must restore the cursor prior to 
	 * returning. 
	 * </pre>
	 * 
	 * @param arguments
	 * The arguments to pass to the function.
	 * @return
	 * The {@code String} result of the function.
	 * @throws IllegalArgumentException
	 * Thrown when the number of arguments does not match the number of parameters for the function.
	 */
	public String invoke(LinkedList<String> arguments) throws IllegalArgumentException;
}